======================
Toolkit Testers' Guide
======================

..
   Use these CSS rules to highlight click targets on GitHub:
   outline: 5px solid yellow;
   background-color: #ff04;

.. note::
   This page is for **Toolkit Testers** specifically.

This is a quick introduction to using the `NG911-Pro GitHub Repository`_. The GitHub repository ("repo") hosts downloadable releases of the Toolkit, the source code, and the issue tracker.

Registration
============

.. sidebar::

   .. figure:: /images/github-404.png
      :alt: Screenshot of a GitHub 404 page
      :height: 250px

      The 404 page an unregistered or unauthorized user might see.

The repo is private, meaning that only authorized GitHub users are able to access it. Anyone who isn't authorized will see a 404 page when visiting the `NG911-Pro GitHub Repository`_.

1. If you do not already have a GitHub account, navigate to https://github.com/signup and follow the instructions to register an account.
2. Once registered, send an email to the people below. **Include your GitHub username.**

`Click here to automatically include the below recipients`_, or add the following manually:

- Emma Baker (ebaker@odot.org)
- Riley Baird (rbaird@odot.org)
- Brittney Williams (Brittney.Williams@odot.ok.gov)
- Colton Snelling (csnelling@odot.org)

You should receive a response in a timely fashion and should not have to repeat this process once complete.

Downloading the Latest Toolkit
==============================

.. image:: /images/tab-code.png
   :alt: GitHub repository navigation bar with "Code" selected
   :target: `NG911-Pro GitHub Repository`_

Go to the `main ("Code") page`_ of the repo. Above the file listing, click the Tags icon.

.. image:: /images/code-tags.png
   :alt: Screenshot indicating the Tags button

Click the first (latest) version.

.. image:: /images/top-release.png
   :alt: Screenshot of available Tags

Under Assets, select the first item, named something like ``NG911.Toolkit.v<version>.zip``

.. image:: /images/assets-download-link.png
   :alt: Screenshot indicating the download link

Unzip the downloaded file. Once unzipped, you may delete the ``.zip`` file. In the unzipped folder, the file ``NG911_GIS_Toolkit_Pro.pyt`` is the ArcGIS Python Toolbox.

.. warning::
   The unzipped folder may be moved in its entirety, but do not move, edit, or delete any of its contents.

.. _label-bug-reports:

Bug Reports & Feature Requests
==============================

.. image:: /images/tab-issues.png
   :alt: GitHub repository navigation bar with "Issues" selected
   :target: Issues_

GitHub's issue tracker is to be used for reporting bugs and submitting **specific, concrete requests** for improvements or additions to the Toolkit. To submit any of these, go to the repo's Issues_ section. To discuss more general ideas for improvements or additions to the Toolkit, see :ref:`label-not-issue-worthy`.

From the following types of issues, determine the one most applicable to your situation, then proceed.

.. topic:: Issue Types and Examples

   .. rubric:: Crash Report

   - Tool crashes or fails unexpectedly
   - Toolbox won't open
   - Tool fails to open

   .. rubric:: Bug Report

   - Tool's interface isn't working correctly
   - Output from a tool is incorrect

   .. rubric:: Improvement Suggestion

   - Provide a better error message for a particular situation
   - Rephrase/clarify a Validation message
   - Rename a parameter to make more sense

   .. rubric:: New Tool Request

   - Automate a time-consuming process not already done by another tool

On the Issues_ page, click *New issue*.

.. image:: /images/new-issue-button.png

Next, you will select the appropriate issue template.

.. image:: /images/new-issue-dialog.png

Fill out the form. If you're submitting a *Bug Report* or *Crash Report*, don't forget to attach your zipped geodatabase if it is relevant; we might not be able reproduce your problem without it!

.. _label-not-issue-worthy:

Feedback That Isn't Issue-Worthy
================================

.. image:: /images/tab-discussions.png
   :alt: GitHub repository navigation bar with "Discussions" selected
   :target: Discussions_

For questions and feedback that doesn't fit into one of the categories under :ref:`label-bug-reports`, consider starting a Discussions_ thread under the most applicable category.

.. topic:: Discussion Categories

   .. rubric:: Ideas

   If you have an action item to share but don't quite have a specific, concrete solution in mind, post under Ideas. (If you *do* have a detailed solution in mind, open an Issue with the Improvement Suggestion template.)

   .. rubric:: Q&A

   For assistance using the Toolkit or interpreting the results of a tool, post under Q&A. Please be sure to include the Toolkit version you are using. By asking questions here, we may be able to identify areas of the documentation, interface, and/or output in need of improvement. You could also check here to see if someone has already gotten an answer to a similar question!

   .. rubric:: General

   For any other feedback that doesn't fit the above categories, post under General.

.. _NG911-Pro GitHub Repository:
.. _main ("Code") page:
   https://github.com/OKDOT-GIS/NG911-Pro

.. _Click here to automatically include the below recipients:
   mailto:ebaker@odot.org;rbaird@odot.org;Brittney.Williams@odot.ok.gov;csnelling@odot.org

.. _Issues:
   https://github.com/OKDOT-GIS/NG911-Pro/issues

.. _Discussions:
   https://github.com/OKDOT-GIS/NG911-Pro/discussions